docs/development/Building in Windows 10 or 11 with Linux Subsystem.md

   1 # Building in Windows 10/11 with Linux subsystem (WSL) [Recommended]
   2
   3 Linux subsystem for Windows (WSL) 10/11 is probably the simplest way of building INAV under Windows.
   4
   5 ## Setting up the environment
   6
   7 Enable WSL:
   8 run `windows features`
   9 enable `windows subsytem for linux`
  10 reboot
  11
  12 Install Ubuntu:
  13 1.  Go to Microsoft store https://www.microsoft.com/en-gb/store/b/home
  14 1.  Search and install most recent Ubuntu LTS version
  15 1.  When download completed, select `Launch Ubuntu`
  16 1.  When prompted enter a user name and password which you will need to remember
  17 1.  When complete, the linux command prompt will be displayed
  18
  19 NOTE: from this point all commands are entered into the Ubunto shell command window
  20
  21 Update the repo packages:
  22 -  `sudo apt update`
  23
  24 Install Git, Make, gcc and Ruby
  25 -  `sudo apt-get install git make cmake ruby`
  26
  27 Install python and python-yaml to allow updates to settings.md
  28 -  `sudo apt-get install python3`
  29
  30 ### CMAKE and Ubuntu 18_04
  31
  32 To run  `cmake` in the latest version you will need to update from Ubuntu `18_04` to `20_04`. The fastest way to do it is to uninstall current version and install `20_04` for Microsoft Store [https://www.microsoft.com/store/productId/9N6SVWS3RX71](https://www.microsoft.com/store/productId/9N6SVWS3RX71)
  33
  34 ## Downloading the INAV repository (example):
  35
  36 Mount MS windows C drive and clone INAV
  37 1.   `cd /mnt/c`
  38 2.   `git clone https://github.com/iNavFlight/inav.git`
  39 3.   `git checkout 6.1.1` (to switch to a specific release tag, for this example INAV version 6.1.1)
  40 4.   `git checkout -b my-branch` (to create own branch)
  41
  42 You are ready!
  43 You now have a folder called inav in the root of C drive that you can edit in windows
  44
  45 ### If you get a cloning error
  46
  47 On some installations, you may see the following error:
  48 ```
  49 Cloning into 'inav'...
  50 error: chmod on /mnt/c/inav/.git/config.lock failed: Operation not permitted
  51 fatal: could not set 'core.filemode' to 'false'
  52 ```
  53
  54 You can fix this with by remounting the drive using the following commands
  55 1. `sudo umount /mnt/c`
  56 2. `sudo mount -t drvfs C: /mnt/c -o metadata`
  57
  58 ## Building with Make (example):
  59
  60 For detailed build instructions see [Building in Linux](Building%20in%20Linux.md)
  61
  62 Launch Ubuntu:
  63 Click Windows Start button then scroll and launch "Ubuntu"
  64
  65 Building from Ubuntu command line
  66
  67 `cd /mnt/c/inav`
  68
  69 Do it onece to prepare build environment
  70 ```
  71 mkdir build
  72 cd build
  73 cmake ..
  74 ```
  75
  76 Then to build
  77 ```
  78 cd build
  79 make MATEKF722
  80 ```
  81
  82 ## Building with Ninja (example):
  83
  84 [Ninja](https://ninja-build.org/) is a popular cross-platform tool. It is both lightweight and executes parallel builds by default. It is advantageous to use this over the old _make_ method. There are detailed instructions for building with Ninja in [Building in Linux](Building%20in%20Linux.md#building-with-ninja).
  85
  86 Launch Ubuntu:
  87 Click Windows Start button. Then scroll and launch **Ubuntu**.
  88
  89 > [!TIP]
  90 > Before using Ninja, you will need to install it. From the Ubuntu command prompt type `sudo apt-get install ninja-build -y` and press enter.
  91
  92 Building from the command line:
  93
  94 First, change to the INAV directory with
  95 ```cd /mnt/c/inav```
  96
  97 Before building, you will need to prepare the build environment. You only need to do this once, unless you reinstall WSL or cmake.
  98
  99 ```
 100 mkdir build
 101 cd build
 102 cmake -GNinja ..
 103 ```
 104
 105 From then on, you can build your target by calling the following from inside the build directory.
 106 ```
 107 ninja MATEKF722
 108 ```
 109
 110 If you want to build multiple targets. You can use:
 111 ```
 112 ninja MATEKF722 MATEKF405SE SPEEDYBEEF405
 113 ```
 114
 115 ## Updating the documents
 116 ```
 117 cd /mnt/c/inav
 118 python3 src/utils/update_cli_docs.py
 119 ```
 120
 121 ## Flashing:
 122 Launch windows configurator GUI and from within the firmware flasher select `Load firmware[Local]`
 123 Hex files can be found in the folder `c:\inav\build`
 124
 125 ## Troubleshooting
 126
 127 ### Syntax error: "(" unexpected
 128
 129 ```
 130 dzikuvx@BerlinAtHome:/mnt/c/Users/pspyc/Documents/Projects/inav/build$ make MATEKF722SE
 131 Generating MATEKF722SE/settings_generated.h, MATEKF722SE/settings_generated.c
 132 /bin/sh: 1: Syntax error: "(" unexpected
 133 make[3]: *** [src/main/target/MATEKF722SE/CMakeFiles/MATEKF722SE.elf.dir/build.make:63: src/main/target/MATEKF722SE/MATEKF722SE/settings_generated.h] Error 2
 134 make[2]: *** [CMakeFiles/Makefile2:33607: src/main/target/MATEKF722SE/CMakeFiles/MATEKF722SE.elf.dir/all] Error 2
 135 make[1]: *** [CMakeFiles/Makefile2:33290: src/main/target/MATEKF722SE/CMakeFiles/MATEKF722SE.dir/rule] Error 2
 136 make: *** [Makefile:13703: MATEKF722SE] Error 2
 137 ```
 138
 139 This error can be triggered by a Windows PATHs included in the Linux Subsystem. The solution is:
 140
 141 #### For WSL V1 - Flags set as 7 by default
 142
 143 1. Open Windows RegEdit tool
 144 1. Find `HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\{GUID}\Flags`
 145 1. Change `Flags` from `7` to `5`
 146 1. Restart WSL and Windows preferably
 147 1. `cd build`
 148 1. `cmake ..`
 149 1. `make {TARGET}` should be working again
 150
 151 #### For WSL V2 - Flags set as 0x0000000f (15) by default
 152 1. Open Windows RegEdit tool
 153 1. Find `HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss\{GUID}\Flags`
 154 1. Change `Flags` from `f` to `d`, it is stored as Base Hexadecimal
 155 1. Restart WSL and Windows preferably
 156 1. `cd build`
 157 1. `cmake ..`
 158 1. `make {TARGET}` should be working again
 159
 160 #### Or, for either version
 161 1. In the Linux Subsystem, `cd /etc/`
 162 2. Create a new file with `sudo nano wsl.conf`
 163 3. Enter the following in to the new file:
 164 ```
 165 [Interop]
 166 appendWindowsPath=false
 167 ```
 168 4. Save the file by holding `Ctrl` and pressing `o`
 169 5. Press `Enter` to confirm the wsl.conf filename.
 170 6. Hit `Ctrl`+`x` to exit nano
 171 7. Restart WSL and Windows preferably
 172 8. `cd build`
 173 9. `cmake ..`
 174 9. `make {TARGET}` should be working again
 175
 176 ### Building targets is very slow
 177 I was pretty shocked when my new i7 -10750 laptop took 25 minutes to build a single target. My old i3-4030 could do the same job in about 2.5 minutes. If you're also suffering from slow builds. Open an elevated PowerShell window and type
 178 ```
 179 wsl -l -v
 180 ```
 181 If you see your Linux distribution is using WSL 2, this is the problem. WSL 2 is quicker than WSL 1 for a lot of things. However, if your files are on a windows mounted drive in Linux, it is extremely slow. There are two options:
 182 1. Put your files on the Linux file system
 183 2. Change to WSL 1
 184
 185 #### Using the Linux file system (recommended)
 186 To use the Linux file system, make sure the distro is running. Open File Explorer and navigate to `\\wsl$`. In that path you will find your distros listed. At this point, map a network drive to your distro. Inside the distro, you can find your home directory at `/home/~username~/`. Create your GitHub folders here.
 187
 188 If after this you have problems with writing to the directories from within VSCode. Open the application for your distro and type
 189 ```
 190 sudo chown -R ~username~ GitHub
 191 ```
 192 `~Username~` is your root distro user that you created and `GitHub` should be the root folder for your GitHub repositories.
 193
 194 #### To switch back to WSL 1
 195 To do this, in the elevated PowerShell window, you can see the name of your distro. Mine is **Ubuntu-20.04**, so I'll use that in this example. Simply type
 196 ```
 197 wsl --set-version Ubuntu-20.04 1
 198 ```
 199 and your distro will be converted to WSL 1. Once finished, reboot your system. Next time you compile a build, it will be faster.